# -*- coding: utf-8 -*-
"""
    xfree.core.auth.authentication
    ~~~~~~~~~~~~~~~~~~~~~
    文件描述：与密码相关的认证服务的接口和服务。
    作者：xfree
    邮箱：cy_83k@qq.com
"""

from abc import ABC, abstractmethod

# 用于管理xfree中密码重置体验的接口
class ResetPasswordService(ABC):
    """
    用于管理xfree中密码重置体验的接口。
    """

    @abstractmethod
    def initiate_password_reset(self, email):
        """
        此方法是抽象的。

        用于向用户发送密码重置令牌。

        在生成令牌时，如果用户请求将重置令牌发送到未在应用程序中注册的电子邮件地址，
        可能会引发 :class:`ValidationError<xfree.core.exceptions.ValidationError>` 异常。

        :param str email: 要发送重置请求的电子邮件地址。
        """
        pass

    @abstractmethod
    def reset_password(self, token, email, new_password):
        """
        此方法是抽象的。

        用于处理密码重置令牌并处理将用户的密码重置为新密码的操作。
        传递给此方法的令牌是发送给用户的原始序列化令牌。

        在解析或使用令牌时，可能会引发
        :class:`TokenError<xfree.core.tokens.TokenError>` 或
        :class:`ValidationError<xfree.core.exceptions.ValidationError>` 异常，
        以传达解析或使用令牌时的失败。

        :param str token: 发送给用户的原始序列化令层
        :param str email: 用户在密码重置时输入的电子邮件地址
        :param str new_password: 要分配给用户的新密码
        """
        pass